<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
	<title>MC Validation Documentation</title>
	<style type="text/css">
	pre {
	display: block;
	background: #eee;
	border: solid 1px;
	padding: 10px;
	}
	</style>
</head>
<body>
	
<h1>MC Validation Documentation</h1>

<p>MC Validation is a Javascript form validation class. It is NOT intended to replace server-side input validation, but rather to supplement it, and provide a better user experience. If you make changes to the class, PLEASE update the docs.</p>

<h2>HTML</h2>
<p>First, you need to link to the validation Javascript file in your <code class="inline">&lt;head&gt;</code>, like so:</p>
<code><pre>
&lt;script src=&quot;mc-validation.js&quot; type=&quot;text/javascript&quot;&gt;&lt;/script&gt;</pre></code>

<p>If you want to display your error messages inline (in the web page and not using an <code class="inline">alert()</code>) then you need to set up a container for them and give it an <code class="inline">id</code>. I do so like this:</p>
<code><pre>
&lt;div id=&quot;msg_area&quot;&gt;&lt;/div&gt;</pre></code>

<p>Then you add an <code class="inline">onSubmit</code> event to your form that will call the function we create later.</p>
<code><pre>
&lt;form action=&quot;process.php&quot; method=&quot;post&quot; onSubmit=&quot;return checkForm(this);&quot;&gt;</pre></code>

<h2>CSS</h2>
<p>You'll probably want to style things at least a little bit. To do so we'll add some CSS declarations.</p>
<code><pre>
#msg_area .error {
	border: solid 2px #892820;
	margin: 3px 0;
	padding: 3px;
	background: #EA6C64
}

.error {
	border: solid 2px #f00;
}</pre></code>

<p>The first block styles the messages that appear in our message area <code>&lt;div&gt;</code>. The second block sets the styling for form fields that have errors.</p>

<h2>Javascript</h2>
<p>Now, the Javascript. This is a little more involed so I'll try and take it one step at a time. I prefer to put my <code>&lt;script&gt;</code> block right under my form. That way the form and it's validation rules are kept together.</p>
<code><pre>
var val; // Make it global. (Don&#039;t loose me!)
function checkForm(obj) {
	if (!val) {
		val = new MC_Validation(obj, &#039;inline&#039;);
		val.setClass(&#039;error&#039;);
		val.setMsgArea(&#039;msg_area&#039;);
	}
	return val.validate();
}</pre></code>

<p>This block so far has instantiated the Validation class, passed it the form object we're working with, and let the message display type to inline. Then it sets the CSS class we'll use on errors to the one we set up just a moment ago. Next it sets the message display area. Last, it runs the validate method and returns the result.</p>

<h3>Error Message Display</h3>
<p>To display messages in an <code>alert()</code> change <code>MC_Validation(obj, &#039;inline&#039;);</code> to <code>MC_Validation(obj, &#039;alert&#039;);</code>.</p>

<p>To prevent messages from being displayed use:</p>
<code><pre>
val.setShowMsgs(false);</pre></code>

<p>To prevent form field highlighting either don't set a CSS class or use:</p>
<code><pre>
val.setClass(&#039;&#039;)</pre></code>

<h3>Validation Rules</h3>
<p>When adding validation rules to form fields there are a number of options you can choose. The simplest way to add a rule is to specify field id and the name of a rule function.</p>
<code><pre>
val.addRules(&#039;field_5&#039;, &#039;alpha&#039;);</pre></code>

<p>Each rule has a default error message. To specify your own error message add it as a third parameter.</p>
<code><pre>
val.addRules(&#039;field_5&#039;, &#039;alpha&#039;, &#039;Field 5 must be alphabetic.&#039;);</pre></code>

<p>If you want to prevent an error message from displaying make the third paramiter <code>'false'</code>.
<code><pre>
val.addRules(&#039;field_5&#039;, &#039;alpha&#039;, &#039;false&#039;);</pre></code>

<p>To apply multiple rules to a single field there are two options. If you would like each rule to display it's own error message, the following will work.</p>
<code><pre>
val.addRules(&#039;field_5&#039;, &#039;alpha&#039;, &#039;Field 5 must be alphabetic.&#039;);
val.addRules(&#039;field_5&#039;, &#039;isNotEmpty&#039;, &#039;Please enter a value for field 5.&#039;);</pre></code>

<p>To apply multiple rules to a single field and display the same error message for any rule that fails, separate rules by a pipe (|).</p>
<code><pre>
val.addRules(&#039;field_5&#039;, &#039;isNotempty|alpha&#039;, &#039;Please enter an alphabetic value for field 5.&#039;);</pre></code>

<h3>Custom Callbacks</h3>
<p>But wait, we're not done. Inevitably there will be cases when you need to perform more complex validation than what this class has built in. To accomplish this, we use callbacks. Write a function and pass it's name as the second parameter.</p>

<p>Our custom function:</p>
<code><pre>
function custom(element) {
	if (element.value != &#039;Hello!&#039;) {
		return &#039;You didn\&#039;t enter Hello!&#039;;
	}
	return &#039;&#039;;
}
</pre></code>

<p>The rule:</p>
<code><pre>
val.addRule(&#039;field_8&#039;, &#039;custom&#039;);
</pre></code>

<p>Thus the end result will be something like this:</p>
<code><pre>
&lt;script type=&quot;text/javascript&quot; language=&quot;Javascript&quot;&gt;
var val; // Make it global. (Don&#039;t loose me!)
function checkForm(obj) {
	if (!val) {
		val = new MC_Validation(obj, &#039;inline&#039;);
		val.setClass(&#039;error&#039;);
		val.setMsgArea(&#039;msg_area&#039;);
	
		val.addRule(&#039;field_1&#039;, &#039;isNotEmpty&#039;, &#039;Please enter your name.&#039;);
		val.addRule(&#039;field_2&#039;, &#039;isNotEmpty|validPhone&#039;);
		val.addRule(&#039;field_3&#039;, &#039;validZip&#039;);
		val.addRule(&#039;field_4&#039;, &#039;validEmail&#039;, &#039;No, no, no. Enter your REAL email address.&#039;);
		val.addRule(&#039;field_5&#039;, &#039;alpha&#039;);
		val.addRule(&#039;field_6&#039;, &#039;alnum&#039;);
		val.addRule(&#039;field_7&#039;, &#039;digits&#039;);
		val.addRule(&#039;field_8&#039;, &#039;custom&#039;); // Use a custom callback
	}
	return val.validate();
}

function custom(element) {
	if (element.value != &#039;Hello!&#039;) {
		return &#039;You didn\&#039;t enter Hello!&#039;;
	}
	return &#039;&#039;;
}
&lt;/script&gt;</pre></code>

<p>For more information look at the source of mc-validation.js</p>

</body>
</html>
